/*
 * 本节将介绍 Orchard Core 如何通过可复用组件 shape 在 UI 上显示各种信息。
 * 相关文档：https://docs.orchardcore.net/en/latest/docs/reference/core/Placement/#shapes
 * 这是 Orchard Core 非常强大且核心的部分，这里你将学习 Display Management 的基础。
 *
 * 为了演示基本功能，我们将创建两个略有不同的页面来显示图书信息。
 */

using Ruitu.Edu.TrainingDemo.Models;
using Microsoft.AspNetCore.Mvc;
using OrchardCore.DisplayManagement;
using OrchardCore.DisplayManagement.ModelBinding;
using System.Threading.Tasks;

namespace Ruitu.Edu.TrainingDemo.Controllers;

/// <summary>
/// 显示管理控制器 - 演示 Orchard Core Shape 及显示管理机制
/// 
/// 主要用途：
/// - 演示 shape 机制和显示管理基础
/// - 展示如何通过 DisplayManager 构建 shape
/// - 演示不同显示类型的 shape 渲染
/// 
/// 使用场景：
/// - 需要灵活渲染对象的 UI 展示
/// - 通过 shape 实现可复用组件
/// 
/// 设计原因：
/// - 利用 shape 实现 UI 组件解耦
/// - 通过显示类型支持多样化展示
/// 
/// 设计模式：
/// - 依赖注入模式：通过构造函数注入显示管理器
/// - shape 模式：通过 shape 实现 UI 复用
/// </summary>
public sealed class DisplayManagementController : Controller, IUpdateModel
{
    // 通过 IDisplayManager<Book> 实现图书对象的显示 shape 构建。
    private readonly IDisplayManager<Book> _bookDisplayManager;

    /// <summary>
    /// 构造函数 - 注入显示管理器
    /// </summary>
    public DisplayManagementController(IDisplayManager<Book> bookDisplayManager) => _bookDisplayManager = bookDisplayManager;

    /// <summary>
    /// 演示 Ad-hoc shape 的创建和使用
    /// 访问路径：/Ruitu.Edu.TrainingDemo/DisplayManagement/AdHocShape
    /// </summary>
    public ActionResult AdHocShape() => View();

    // 下一站：Views/DisplayManagement/AdHocShape.cshtml

    /// <summary>
    /// 显示图书摘要及附加信息页面
    /// 访问路径：/Ruitu.Edu.TrainingDemo/DisplayManagement/DisplayBook
    /// </summary>
    public async Task<IActionResult> DisplayBook()
    {
        // 创建演示用图书对象。
        var book = CreateDemoBook();
        // 生成用于显示的 shape。
        var shape = await _bookDisplayManager.BuildDisplayAsync(book, this);
        // 下一站：Views/DisplayManagement/DisplayBook.cshtml
        return View(shape);
    }

    /// <summary>
    /// 显示带有显示类型的图书 shape
    /// 访问路径：/Ruitu.Edu.TrainingDemo/DisplayManagement/DisplayBookDescription
    /// </summary>
    public async Task<IActionResult> DisplayBookDescription()
    {
        var book = CreateDemoBook();
        // 指定显示类型，Orchard Core 会查找 [ClassName].[DisplayType].cshtml
        var shape = await _bookDisplayManager.BuildDisplayAsync(book, this, "Description");
        // 下一站：Views/Book.Description.cshtml
        return View(shape);
    }

    /// <summary>
    /// 创建演示用图书对象
    /// </summary>
    private static Book CreateDemoBook() =>
        new()
        {
            CoverPhotoUrl = "/Ruitu.Edu.TrainingDemo/images/HarryPotter.jpg",
            Title = "Harry Potter and The Sorcerer's Stone",
            Author = "J.K. (Joanne) Rosenzweig",
            Description = "Harry hasn't had a birthday party in eleven years - but all that is about to change " +
                "when a mysterious letter arrives with an invitation to an incredible place.",
        };
}

// 完成所有操作后可进入下一个训练。
// 训练部分结束：显示管理
// 下一站：Controllers/DatabaseStorageController
